This readme file contains additional information about the "DeskCover" and "ColorCover" XCMDs.
"Error codes"
Here is a listing of the error codes that the XCMDs may return in the result if problems are encountered.
"DeskTopIsAlreadyCovered"
-- the desktop is already covered. Generally you shouldn't have to check for this. "DeskCover" or "ColorCover" won't cover the desktop a second time.
"DeskCoverFailed"
"ColorCoverFailed"
-- for some reason the backdrop could not be created. This would probably be related to insufficient memory. However, since the XCMDs use very little RAM, this should occur only in extreme circumstances. Try giving HC more memory.
"IncorrectPatternName"
-- "DeskCover" was given an invalid entry for "thePattern" parameter.
No error code is returned from "ColorCover" if 32 bit QuickDraw is not available. The XCMD simply tries to make a black backdrop. If it doesn't succeed then it returns "ColorCoverFailed" in the result.
Of course, the XCMDs might fail for other reasons. Send your bug reports to the email address shown at the top of this file.
"Color Availability"
On monitors running thousands or millions of colors, the color you select for the "ColorCover" backdrop should always show correctly. If your monitor shows only 256 colors, there are some rare circumstances where you might not get what you expect. The foreground HyperCard window gets first crack at the available colors on your system. If the foreground window uses all 256 colors, the color of the backdrop will be mapped to the closest foreground color. This might cause a problem if, for example, you display a pict on the foreground that uses a custom color palette made up exclusively of 256 blue shades (actually, there would be 254 shades, since black and white should always be available). If you had wanted the backdrop to be a bright red, it would, instead, show up as the "nearest" shade of blue! If this is a problem, you will have to alter the pict and reserve at least one palette color for the backdrop.
"DCBackgroundWnd"
Both XCMDs create an external window named "DCBackgroundWnd" (the long, odd name was chosen to make it unlikely that there would be a conflict because of another window having the same name). This means that you can close the window from a script, using the command "close window DCBackgroundWnd". Knowing the window's name may be useful if you have a script that manipulates windows, or if you will be using several stacks at the same time, and would like to be able to close the backdrop from a stack that does not have one of the XCMDs installed. Keep in mind, however, that the menu management functions of the XCMDs will not operate if you close the backdrop in this fashion.
"Quirks"
There are rare cases where calling an XCMD that does something to the screen, immediately after calling DeskCover or ColorCover, can turn the card window white. When the second XCMD exits, the card window finishes its redraw and assumes its normal appearance. If you experience this problem, introduce a wait of at least 5 ticks after calling DeskCover. This allows the card window to complete its redraw.
on openStack
DeskCover on, black
wait 5
otherXCMD
end openStack
"Peeking" at the scripts
If you have the colorized version of the stack (titled "DeskCover/ColorCover1.1c) and you are running HyperCard 2.2, the stack will disable and "gray out" buttons when appropriate. "Peeking" at scripts shows the script editor menubar, which can "confuse" the handlers that enable and disable the "HideBars" and "ShowBars" buttons. Therefore, when running under HyperCard 2.2, the cantPeek property of the stack will be set to true. If you wish to look at the scripts, simply use the message box either to set the cantPeek property to false, or to enter an "edit script of <whatever>" command.
"Custom Versions"
These XCMDs have been written to be useable under a wide range of conditions. If you have special requirements, please contact me. If you know precisely the conditions under which your stack will be running, I have specialized versions that take up only 1 to 2 k of disk space. If I have something "in stock" that fits your requirements, I will generally charge only $15 more that the standard fees listed in the stack
